Este guia implementa, em ordem, todo o contrato público. Ao final, sua aplicação autentica, cadastra os endereços, faz a cotação, cria o envio, emite e baixa a etiqueta, trabalha com DACE quando o envio for elegível e consulta o rastreamento.
Guias de apoio: autenticação, remetente e destinatário, cotações, criação do envio, emissão e download, DACE e rastreamento.
1. Crie e ative sua conta
- Crie uma conta grátis.
- Informe os dados de pessoa física ou jurídica.
- Confirme o e-mail para ativar a conta.
- Use na API o mesmo e-mail e a mesma senha usados no painel.
A API documentada usa o endereço de produção informado na próxima etapa.
2. Configure os segredos
API_URL=https://api.enviofacilencomendas.com.br
ACCOUNT_EMAIL=voce@empresa.com.br
ACCOUNT_PASSWORD=segredoMantenha esses valores somente no backend ou em um gerenciador de segredos.
3. Faça login
curl -X POST "$API_URL/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{
"email": "integracao@empresa.com.br",
"senha": "SENHA_ARMAZENADA_COM_SEGURANCA"
}'Persista accessToken, refreshToken e um lojas[].id. O campo do login é
senha.
4. Envie os headers da loja
Nas operações seguintes:
Authorization: Bearer <accessToken>
X-Tenant-Id: <lojas[].id>Nunca use o nome da loja no lugar do identificador.
5. Cadastre ou reutilize o remetente
Primeiro consulte os remetentes já salvos:
curl "$API_URL/api/v1/addresses?q=Matriz&page=1&pageSize=20" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Id: $LOJA_ID"Se o remetente ainda não existir, cadastre-o com o endereço completo:
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",
"country": "BR",
"setAsDefault": true
}'6. Cadastre ou reutilize o destinatário
Consulte os destinatários salvos com
GET /api/v1/recipients?q=Maria&page=1&pageSize=20. Cadastre quando não
encontrar o registro correto:
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",
"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"
}
}'Veja a descrição de cada campo e os formatos das respostas em Remetente e destinatário.
7. Faça uma cotação
curl -X POST "$API_URL/api/v1/quotes/simulate" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Id: $LOJA_ID" \
-H "Content-Type: application/json" \
-d '{
"originCep": "01310100",
"destinationCep": "20040020",
"peso": 1.5,
"comprimento": 30,
"largura": 20,
"altura": 10,
"valorDeclarado": 89.9,
"hasPackaging": true,
"format": "2"
}'Persista quoteId, carrierId, serviceLevelId e expiresAt da opção
selecionada.
8. Crie o envio pela API
Envie os identificadores da cotação, os endereços completos e o mesmo pacote usado na simulação:
curl -X POST "$API_URL/api/v1/shipments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Id: $LOJA_ID" \
-H "Content-Type: application/json" \
-d '{
"externalRef": "PEDIDO-1001",
"quoteId": "64b232e7-8f9c-4d65-bb1d-95bf5c21ea46",
"carrierId": "aaf3b0d6-bf2a-4af0-bb97-bd056a749ad1",
"serviceLevelId": "22222222-2222-4222-8222-222222222222",
"originAddress": {
"name": "Matriz São Paulo",
"personName": "João Silva",
"phone": "11999999999",
"street": "Avenida Paulista",
"number": "1000",
"district": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"zip": "01310100",
"cpfCnpj": "11222333000181",
"country": "BR"
},
"destAddress": {
"name": "Maria Oliveira",
"personName": "Maria Oliveira",
"phone": "21999999999",
"street": "Rua do Mercado",
"number": "45",
"district": "Centro",
"city": "Rio de Janeiro",
"state": "RJ",
"zip": "20040020",
"cpfCnpj": "52998224725",
"country": "BR"
},
"parcel": {
"format": "2",
"weightKg": 1.5,
"lengthCm": 30,
"widthCm": 20,
"heightCm": 10,
"declaredValueCents": 8990,
"hasPackaging": true,
"contentDescription": "Vestuário",
"products": [
{
"content": "Camiseta de algodão",
"quantity": 1,
"valueCents": 8990,
"ncm": "61091000"
}
]
},
"invoice": {
"type": "DCE",
"valor": 89.9
}
}'A resposta 201 contém shipmentId. Persista esse identificador e use-o na
emissão. Veja todos os campos, formatos de pacote e exemplo com NF-e em
Criar envio.
9. Emita a etiqueta
curl -X POST "$API_URL/api/v1/labels/shipments/6a4eaf6d-d962-4b0c-a421-f2d426128e92/emit" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Id: $LOJA_ID" \
-H "Content-Type: application/json" \
-d '{
"paymentMethod": "wallet"
}'wallet paga a emissão com o saldo disponível da loja.
Em 200, persista labelId, trackingCode e transactionId. Em 202, persista providerJobId e não repita a emissão.
10. Baixe a etiqueta
curl "$API_URL/api/v1/labels/ID_DA_ETIQUETA/download" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Id: $LOJA_ID"A resposta contém downloadUrl. A URL é temporária: baixe o arquivo imediatamente e não a use como identificador permanente.
11. Gere o DACE quando aplicável
curl -X POST "$API_URL/api/v1/fiscal-documents/shipments/ID_DO_ENVIO/dace" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Id: $LOJA_ID" \
-H "Content-Type: application/json" \
-d '{ "tipoDace": "R" }'O envio precisa ter etiqueta emitida e uma DC-e apta. Se available for false, não force novas tentativas.
12. Consulte o rastreamento
curl "$API_URL/api/v1/tracking/code/CODIGO_DE_RASTREIO?refresh=false" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Id: $LOJA_ID"Use refresh=true somente quando precisar consultar o provedor naquele momento.
13. Renove a sessão
curl -X POST "$API_URL/api/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{ "token": "REFRESH_TOKEN_MAIS_RECENTE" }'Substitua os dois tokens de forma atômica e descarte o refresh token anterior.
Pronto para produção quando
- os segredos não aparecem em código ou logs;
- a loja é isolada por
X-Tenant-Id; - remetentes e destinatários não são cadastrados em duplicidade;
- a emissão
200e202é reconciliada sem cobrança duplicada; - etiqueta e DACE são baixados antes da expiração;
- o polling de rastreamento usa backoff;
- erros
401,403,404,409,422,429e5xxforam testados.