Remetente e destinatário

Cadastre os dados de origem e entrega na loja indicada por X-Tenant-Id. Esses dados ficam salvos para serem selecionados ao preparar o envio.

Todas as operações desta página exigem:

Authorization: Bearer <accessToken>
X-Tenant-Id: <lojas[].id>

Cadastre o remetente

Use um remetente para cada endereço de postagem da empresa.

POST /api/v1/addresses
Content-Type: application/json

{
  "name": "Matriz São Paulo",
  "personName": "João Silva",
  "company": "Loja Exemplo Ltda.",
  "phone": "11999999999",
  "email": "expedicao@empresa.com.br",
  "street": "Avenida Paulista",
  "number": "1000",
  "complement": "Conjunto 101",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "zip": "01310100",
  "cpfCnpj": "11222333000181",
  "ieNumber": "110042490114",
  "country": "BR",
  "setAsDefault": true
}

Exemplo com cURL:

curl -X POST "$API_URL/api/v1/addresses" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Tenant-Id: $LOJA_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Matriz São Paulo",
    "personName": "João Silva",
    "company": "Loja Exemplo Ltda.",
    "phone": "11999999999",
    "email": "expedicao@empresa.com.br",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Conjunto 101",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01310100",
    "cpfCnpj": "11222333000181",
    "ieNumber": "110042490114",
    "country": "BR",
    "setAsDefault": true
  }'

Campos do remetente:

Campo	Obrigatório	Como enviar
`name`	Sim	Nome interno para identificar o remetente.
`personName`	Não	Pessoa responsável pela postagem.
`company`	Não	Razão social ou nome da empresa.
`phone`	Sim	Telefone de contato do remetente.
`email`	Não	E-mail válido de contato.
`street`	Sim	Logradouro sem o número.
`number`	Sim	Número do imóvel.
`complement`	Não	Sala, conjunto, bloco ou outra referência.
`district`	Sim	Bairro.
`city`	Sim	Cidade.
`state`	Sim	UF com duas letras, por exemplo `SP`.
`zip`	Sim	CEP com oito dígitos, sem hífen.
`cpfCnpj`	Sim	CPF com 11 ou CNPJ com 14 dígitos.
`ieNumber`	Não	Inscrição estadual, quando aplicável.
`country`	Não	Código ISO de duas letras. O padrão é `BR`.
`setAsDefault`	Não	`true` para torná-lo o remetente padrão da loja.

A resposta 201 devolve o remetente salvo. Guarde o id se sua aplicação mantiver uma referência local.

{
  "id": "6f62128f-1533-4f77-a320-58029fc51264",
  "lojaId": "f73b3723-2fe9-4239-a4e6-4c9fc463497d",
  "addressType": "SENDER",
  "name": "Matriz São Paulo",
  "personName": "João Silva",
  "company": "Loja Exemplo Ltda.",
  "phone": "11999999999",
  "email": "expedicao@empresa.com.br",
  "street": "Avenida Paulista",
  "number": "1000",
  "complement": "Conjunto 101",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "zip": "01310100",
  "cpfCnpj": "11222333000181",
  "ieNumber": "110042490114",
  "country": "BR",
  "isDefault": true,
  "createdAt": "2026-07-29T14:30:00.000Z",
  "updatedAt": "2026-07-29T14:30:00.000Z"
}

Consulte os remetentes salvos

GET /api/v1/addresses?q=Matriz&page=1&pageSize=20

q filtra os remetentes salvos. page começa em 1 e pageSize aceita de 1 a 100.

{
  "data": [
    {
      "id": "6f62128f-1533-4f77-a320-58029fc51264",
      "lojaId": "f73b3723-2fe9-4239-a4e6-4c9fc463497d",
      "addressType": "SENDER",
      "name": "Matriz São Paulo",
      "personName": "João Silva",
      "company": "Loja Exemplo Ltda.",
      "phone": "11999999999",
      "email": "expedicao@empresa.com.br",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Conjunto 101",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01310100",
      "cpfCnpj": "11222333000181",
      "ieNumber": "110042490114",
      "country": "BR",
      "isDefault": true,
      "createdAt": "2026-07-29T14:30:00.000Z",
      "updatedAt": "2026-07-29T14:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

Cadastre o destinatário

Os dados de contato ficam no destinatário. O campo address contém o endereço de entrega.

POST /api/v1/recipients
Content-Type: application/json

{
  "name": "Maria Oliveira",
  "cpfCnpj": "52998224725",
  "phone": "21999999999",
  "email": "maria@example.com",
  "notes": "Receber na portaria",
  "address": {
    "name": "Casa",
    "personName": "Maria Oliveira",
    "phone": "21999999999",
    "email": "maria@example.com",
    "street": "Rua do Mercado",
    "number": "45",
    "complement": "Apto 302",
    "district": "Centro",
    "city": "Rio de Janeiro",
    "state": "RJ",
    "zip": "20040020",
    "country": "BR"
  }
}

Exemplo com cURL:

curl -X POST "$API_URL/api/v1/recipients" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Tenant-Id: $LOJA_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Oliveira",
    "cpfCnpj": "52998224725",
    "phone": "21999999999",
    "email": "maria@example.com",
    "notes": "Receber na portaria",
    "address": {
      "name": "Casa",
      "personName": "Maria Oliveira",
      "phone": "21999999999",
      "email": "maria@example.com",
      "street": "Rua do Mercado",
      "number": "45",
      "complement": "Apto 302",
      "district": "Centro",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "zip": "20040020",
      "country": "BR"
    }
  }'

Campos do destinatário:

Campo	Obrigatório	Como enviar
`name`	Sim	Nome do destinatário.
`cpfCnpj`	No Brasil	CPF com 11 ou CNPJ com 14 dígitos.
`phone`	Sim	Telefone para contato sobre a entrega.
`email`	Não	E-mail válido do destinatário.
`notes`	Não	Observação operacional sobre a entrega.
`address`	Sim	Objeto com o endereço de entrega.

Campos de address:

Campo	Obrigatório	Como enviar
`name`	Sim	Nome interno do endereço, como `Casa`.
`personName`	Sim	Nome que será usado na entrega.
`phone`	Sim	Telefone de contato nesse endereço.
`email`	Não	E-mail de contato nesse endereço.
`street`	Sim	Logradouro sem o número.
`number`	Sim	Número do imóvel.
`complement`	Não	Apartamento, bloco ou outra referência.
`district`	Sim	Bairro.
`city`	Sim	Cidade.
`state`	Sim	UF com duas letras, por exemplo `RJ`.
`zip`	Sim	CEP com oito dígitos, sem hífen.
`country`	Sim	Código ISO de duas letras, por exemplo `BR`.

A resposta 201 contém o id do destinatário e o addressId do endereço associado:

{
  "id": "2fdaf2c6-28bd-4a91-b229-20c3bc693b8a",
  "lojaId": "f73b3723-2fe9-4239-a4e6-4c9fc463497d",
  "name": "Maria Oliveira",
  "cpfCnpj": "52998224725",
  "phone": "21999999999",
  "email": "maria@example.com",
  "notes": "Receber na portaria",
  "addressId": "657eb022-6456-4811-aa09-ffb749852a25",
  "lastUsedAt": null,
  "createdAt": "2026-07-29T14:35:00.000Z",
  "updatedAt": "2026-07-29T14:35:00.000Z",
  "address": {
    "id": "657eb022-6456-4811-aa09-ffb749852a25",
    "name": "Casa",
    "personName": "Maria Oliveira",
    "phone": "21999999999",
    "email": "maria@example.com",
    "street": "Rua do Mercado",
    "number": "45",
    "complement": "Apto 302",
    "district": "Centro",
    "city": "Rio de Janeiro",
    "state": "RJ",
    "zip": "20040020",
    "country": "BR"
  }
}

Consulte os destinatários salvos

GET /api/v1/recipients?q=Maria&page=1&pageSize=20

q pesquisa por nome, documento ou contato. A resposta usa a mesma estrutura do cadastro dentro de data:

{
  "data": [
    {
      "id": "2fdaf2c6-28bd-4a91-b229-20c3bc693b8a",
      "lojaId": "f73b3723-2fe9-4239-a4e6-4c9fc463497d",
      "name": "Maria Oliveira",
      "cpfCnpj": "52998224725",
      "phone": "21999999999",
      "email": "maria@example.com",
      "notes": "Receber na portaria",
      "addressId": "657eb022-6456-4811-aa09-ffb749852a25",
      "lastUsedAt": null,
      "createdAt": "2026-07-29T14:35:00.000Z",
      "updatedAt": "2026-07-29T14:35:00.000Z",
      "address": {
        "id": "657eb022-6456-4811-aa09-ffb749852a25",
        "name": "Casa",
        "personName": "Maria Oliveira",
        "phone": "21999999999",
        "email": "maria@example.com",
        "street": "Rua do Mercado",
        "number": "45",
        "complement": "Apto 302",
        "district": "Centro",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "zip": "20040020",
        "country": "BR"
      }
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

Regras de preenchimento

Envie CEP, CPF e CNPJ somente com dígitos.
Para endereços brasileiros, envie a UF com duas letras.
Use o código ISO de duas letras em country.
Não misture o número ou o complemento com street.
Consulte os registros salvos antes de cadastrar novamente.
Use sempre o X-Tenant-Id da loja à qual o endereço pertence.

Faça uma cotação →