Endereços no Brasil

Os endereços da API seguem o formato dos Correios. Você só precisa enviar três campos: o nome de quem recebe, o CEP e o número. O resto a CartaFlow completa a partir do CEP.

A regra do endereçoCopiar link da seção

• Obrigatórios: name, postal_code e number.
• Os campos que você envia são usados como vieram. A CartaFlow não troca o seu bairro nem o seu logradouro pelo que está na base de CEPs.
• Os campos que você não envia são preenchidos a partir do CEP: street, neighborhood, city e state.
• Se um campo não vier e o CEP não o informar, a API responde 422 com o código address_incomplete e nada é criado nem cobrado. Acontece com CEPs que valem para uma cidade inteira, comuns em cidades pequenas, que não têm logradouro nem bairro.

A mesma regra vale para o destinatário e o remetente de uma correspondência (to e from) e para o endereço de uma verificação.

O endereço mais curtoCopiar link da seção

"to": {
  "name": "Destinatário Exemplo",
  "postal_code": "01001-000",
  "number": "128",
  "complement": "Ap. 52"
}

A correspondência volta com o endereço completo, como será impresso:

"to": {
  "name": "Destinatário Exemplo",
  "street": "Praça da Sé",
  "number": "128",
  "complement": "Ap. 52",
  "neighborhood": "Sé",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01001-000"
}

Parte do endereço vem de você, parte do CEPCopiar link da seção

Se o seu cadastro tem o bairro do jeito que o cliente escreveu, envie. A CartaFlow usa o seu bairro e busca só o que faltou.

"to": {
  "name": "Destinatário Exemplo",
  "postal_code": "01001-000",
  "number": "128",
  "neighborhood": "Centro"
}

"to": {
  "name": "Destinatário Exemplo",
  "street": "Praça da Sé",
  "number": "128",
  "complement": null,
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01001-000"
}

O logradouro, a cidade e a UF vieram do CEP. O bairro é o que você enviou.

O endereço completoCopiar link da seção

Quando você já tem todos os campos, envie todos. Nada é buscado.

"to": {
  "name": "Destinatário Exemplo",
  "street": "Rua Exemplo",
  "number": "128",
  "complement": "Ap. 52",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01001-000"
}

Os camposCopiar link da seção

Nas respostas, todos os campos aparecem sempre. complement vale null quando o endereço não tem complemento.

UFsCopiar link da seção

Preencha o formulário do seu cliente pelo CEPCopiar link da seção

GET /v1/postal-codes/{postal_code} devolve o logradouro, o bairro, a cidade e a UF de um CEP. É a mesma consulta que a API faz para completar os endereços. Não tem custo.

curl "https://api.cartaflow.com.br/v1/postal-codes/01001-000" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

{
  "object": "postal_code",
  "postal_code": "01001-000",
  "street": "Praça da Sé",
  "neighborhood": "Sé",
  "city": "São Paulo",
  "state": "SP"
}

street e neighborhood valem null quando o CEP vale para a cidade inteira. Nesse caso, peça o logradouro e o bairro ao seu cliente e envie os dois na correspondência.

RemetenteCopiar link da seção

O remetente é impresso em uma linha acima do destinatário. É para onde os Correios devolvem a correspondência quando não conseguem entregar.

• Envie from na correspondência para usar um remetente específico, com a mesma regra de campos do destinatário.
• Se você não enviar from, usamos o remetente padrão da conta, que você define no painel em Configurações > Empresa. Ele aparece em default_sender de GET /v1/account.

Só endereços no BrasilCopiar link da seção

A CartaFlow imprime e posta no Brasil, para endereços no Brasil. Por isso não existe campo de país, e o CEP é sempre obrigatório.

Erros de endereçoCopiar link da seção

Problemas de endereço chegam como 422 validation_error, com um item em details para cada campo. O param mostra o campo, por exemplo to.postal_code ou from.street.

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameters",
    "message": "Um campo tem problema. Veja details.",
    "request_id": "req_9Vb4Xk2Lq8Mz",
    "doc_url": "https://docs.cartaflow.com.br/errors#invalid_parameters",
    "details": [
      {
        "param": "to.street",
        "code": "address_incomplete",
        "message": "O CEP 13165-000 vale para a cidade inteira e não informa o logradouro. Envie street e neighborhood."
      }
    ]
  }
}

A lista completa de códigos está em Erros.