​

Verificar o titular da conta

​

Como funciona

​

Enviar os dados

curl -X POST "https://pilotstatus.com.br/v1/phone-lines/verification" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -H "Idempotency-Key: 5f0c6d2e-9a41-4d1b-8f7e-2b3c4d5e6f70" \
  -H "Content-Type: application/json" \
  -d "{
    \"documentType\": \"CNPJ\",
    \"documentNumber\": \"11.222.333/0001-81\",
    \"contactEmail\": \"ana@example.com\",
    \"contactWhatsapp\": \"+55 11 90000-0000\",
    \"document\": \"data:application/pdf;base64,$(base64 -w0 cartao-cnpj.pdf)\"
  }"

{
  "status": "PENDING_CONTACT",
  "canPurchase": false,
  "verification": {
    "id": "cmg5k0v3r0000vf8example7k",
    "documentType": "CNPJ",
    "documentNumber": "**.***.333/0001-**",
    "legalName": "ACME LTDA",
    "contact": {
      "email": "a***@example.com",
      "whatsapp": "+5511****0000",
      "requiredChannels": ["WHATSAPP", "EMAIL"],
      "confirmedChannels": [],
      "pendingChannels": ["WHATSAPP", "EMAIL"]
    },
    "document": { "status": "RECEIVED" },
    "reviewReason": null,
    "reviewNote": null,
    "createdAt": "2026-10-01T13:55:02.000Z",
    "updatedAt": "2026-10-01T13:55:09.000Z"
  }
}

​

Confirmar um código

curl -X POST "https://pilotstatus.com.br/v1/phone-lines/verification/contact/email/confirm" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482913" }'

{
  "status": "APPROVED",
  "canPurchase": true,
  "verification": {
    "id": "cmg5k0v3r0000vf8example7k",
    "documentType": "CNPJ",
    "documentNumber": "**.***.333/0001-**",
    "legalName": "ACME LTDA",
    "contact": {
      "email": "a***@example.com",
      "whatsapp": "+5511****0000",
      "requiredChannels": ["WHATSAPP", "EMAIL"],
      "confirmedChannels": ["WHATSAPP", "EMAIL"],
      "pendingChannels": []
    },
    "document": { "status": "RECEIVED" },
    "reviewReason": null,
    "reviewNote": null,
    "createdAt": "2026-10-01T13:55:02.000Z",
    "updatedAt": "2026-10-01T13:57:31.000Z"
  }
}

• Um código expira 10 minutos depois de enviado (400 CONTACT_CODE_EXPIRED).
• Um código errado é 400 CONTACT_CODE_INVALID e conta como tentativa; depois de 5 tentativas erradas o código é bloqueado (429 CONTACT_CODE_TOO_MANY_ATTEMPTS) — peça um novo.
• Um código só vale uma vez. Repetir uma confirmação que já deu certo responde CONTACT_CODE_INVALID: nesse caso, leia o estado com GET.
• Um canal fora de requiredChannels é 400 CONTACT_CODE_NOT_REQUIRED. Sem nenhuma verificação, 404 VERIFICATION_NOT_FOUND.

​

Enviar um novo código

• No máximo um código por canal a cada 60 segundos, contando o que o envio dos dados mandou (429 CONTACT_CODE_COOLDOWN).
• Só enquanto a verificação está em PENDING_CONTACT (409 VERIFICATION_WRONG_STATE depois disso), e só em um canal de requiredChannels (400 CONTACT_CODE_NOT_REQUIRED).
• 503 SUPPLIER_UNAVAILABLE: não foi possível colocar o código na fila de envio. Nada conta para o intervalo de 60 segundos — tente de novo.

​

Enviar um novo documento

• PENDING_CONTACT — para substituir o documento que você enviou. Faça isso quando document.status for UNREADABLE ou UNCLEAR: não conseguimos ler do arquivo um número confiável, então envie uma foto mais nítida ou o PDF. Se você confirmar o último código sem substituí-lo, a verificação vai para análise manual (IN_REVIEW, reviewReason: "DOCUMENT_CHECK").
• NEEDS_DOCUMENT — o revisor pediu outro documento (reviewNote pode dizer qual). Os códigos de contato já foram confirmados, então o novo documento leva a verificação direto a uma nova decisão, nesta mesma resposta.

​

Ler o estado

{ "status": "NONE", "canPurchase": false, "verification": null }

​

O objeto de estado

​

Idempotência

• Mesma chave, mesma requisição, a primeira já terminou → 200 (não 201) com o estado atual do workspace e o header Idempotent-Replayed: true. Nada é enviado nem lido de novo.
• Mesma chave enquanto a primeira ainda está rodando → 409 IDEMPOTENCY_KEY_IN_USE. Aguarde e envie de novo para receber o resultado.
• Mesma chave, requisição diferente (qualquer campo, inclusive o arquivo) → 409 IDEMPOTENCY_KEY_REUSED. Use uma chave nova para dados novos.
• Uma requisição recusada como um todo (qualquer resposta 4xx ou 5xx) não guarda nada: a mesma chave pode ser enviada de novo, e roda.

​

Limites

• 10 envios por hora por workspace, somando o envio dos dados e o de documento → 429 RATE_LIMITED, com o header Retry-After (em segundos) e retryAfterSeconds no corpo. Uma requisição recusada pela validação antes de rodar — campo, tipo ou arquivo errado — não conta.
• Códigos de contato: valem 10 minutos, aceitam 5 tentativas erradas cada, um por canal a cada 60 segundos.
• O arquivo: PDF, JPEG, PNG ou WEBP, com no máximo 10 MB.

​

Privacidade

​

Erros