Documentação da API

Obter acesso à API

1. Peça ao suporte para abrir uma conta para você.
2. Envie ao suporte os serviços de que você precisa, a sua conta e os IPs de saída dos seus servidores.
3. Em seguida, emitimos uma chave de API e o guia de integração completo. As chaves valem de 1 a 730 dias, e cada chave aceita até 32 IPs de saída.

Informações básicas

Autenticação

Envie Authorization: Bearer <chave de API> em todas as requisições

User-Agent

Obrigatório. Requisições sem ele são bloqueadas pela Cloudflare (error 1010)

Formato

Requisições e respostas em JSON, em UTF-8, exceto no envio de arquivos

Horário

Timestamps Unix em UTC, em milissegundos

Valores

Até oito casas decimais. Use um tipo decimal e não arredonde para duas casas

Fluxo de integração

1. Liste os serviços e consulte seu saldo. Guarde o productId de que você precisa.
2. Leia a declaração de uso de dados e aceite-a, se ainda não tiver aceitado.
3. Envie o arquivo de números e guarde o fileId retornado.
4. Obtenha uma cotação com o productId e o fileId. Confira a quantidade, o preço unitário e o total.
5. Crie e armazene uma chave de idempotência e depois faça o pedido. Isso cobra do seu saldo.
6. Configure um webhook para receber as mudanças de status e faça a conciliação com updatedSince a cada 5–10 minutos para não perder nada.
7. Quando o pedido for concluído, liste os arquivos de resultado, baixe todos e confira o sha256 de cada um. Baixe também os sem sucesso.

Exemplo com curl

Substitua os placeholders. Os parâmetros completos de cotação e pedido estão no guia que você recebe com o acesso.

1. Defina sua chave e liste os serviços

   Copiar

   export CHECKIM_TOKEN='substitua pela chave de API fornecida pelo suporte'
   export CHECKIM_BASE='https://api.checkim.ai/openapi/v1'
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/products"

2. Envie um arquivo de números

   Copiar

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -F 'file=@./numbers.csv;type=text/csv' \
     "$CHECKIM_BASE/files"

3. Obtenha uma cotação

   Copiar

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"productId":"<productId>","name":"batch-001","fileId":"<fileId>"}' \
     "$CHECKIM_BASE/orders/check"

4. Faça o pedido

   Copiar

   # Cobra do seu saldo. Mantenha a chave e o corpo idênticos ao tentar novamente.
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: partner-request-001' \
     -d '{"quoteId":"<quoteId>","clientOrderId":"partner-batch-001"}' \
     "$CHECKIM_BASE/orders"

5. Consulte um pedido ou concilie pelo horário de alteração

   Copiar

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     "$CHECKIM_BASE/orders?updatedSince=<UTC ms>&size=100"

6. Liste e baixe os resultados e confira o sha256

   Copiar

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>/results"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" -o result.csv \
     "$CHECKIM_BASE/orders/<orderId>/results/<fileId>/download"
   shasum -a 256 result.csv

Endpoints

Listar e conciliar pedidos

• Os pedidos são listados do mais recente para o mais antigo. Quando uma página trouxer nextCursor, envie-o como cursor para obter a próxima; a paginação por cursor nunca pula nem repete pedidos, mesmo com novos chegando.
• Filtre por status e por data de criação (createdFrom, createdTo, em milissegundos UTC), ou busque um pedido pelo clientOrderId.
• updatedSince retorna apenas os pedidos cujo status mudou depois desse horário, da mudança mais antiga para a mais recente. Consulte com regularidade e um webhook perdido nunca fará você perder um status.

Baixar resultados

• Cada arquivo da lista de resultados tem um sha256. O ETag do download é o mesmo valor, então compare depois de baixar.
• Requisições com Range retomam um download. Antes, confira se o sha256 não mudou; se mudou, o arquivo foi regerado e você precisa baixá-lo inteiro de novo.
• Se você já tem o arquivo completo, envie If-None-Match: se nada mudou, a resposta é 304 sem corpo.
• Pedidos grandes com entrega em lotes listam os lotes concluídos durante a execução; o arquivo final, após a conclusão, é a versão oficial.
• Nos serviços com foto de perfil (verificação avançada ou de gênero e idade do Telegram e do WhatsApp), a coluna avatar do CSV de resultado traz um link de imagem assinado que pode ser aberto diretamente com GET enquanto os resultados estiverem disponíveis (sem enviar o cabeçalho Authorization; aceita If-None-Match).

Webhooks

• Quando o status de um pedido feito pela API muda, enviamos um evento por POST para a sua URL HTTPS. Exige a permissão webhook:manage.
• Cada evento traz o cabeçalho CheckIM-Signature (t=timestamp,v1=assinatura). Verifique-o com HMAC-SHA256 de "t.corpo bruto da requisição" usando o seu segredo de assinatura.
• Qualquer 2xx conta como entregue; falhas são repetidas 9 vezes ao longo de cerca de 2 dias. Você pode receber um evento mais de uma vez, então elimine duplicados pelo id.
• As requisições saem do IP fixo 34.21.195.36, então você pode liberar apenas esse endereço.

Status dos pedidos

Limites e observações

• Por padrão, no máximo 1.200 requisições por minuto por IP de saída, 240 por conta e 120 por chave. Os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset mostram quantas restam neste minuto.
• Cotações e envios de arquivo são lentos, então cada conta pode ter no máximo 3 em andamento ao mesmo tempo. Os demais recebem 429 TOO_MANY_CONCURRENT_REQUESTS.
• Ao receber 429 ou 503, aguarde os segundos indicados em Retry-After e repita a mesma requisição.
• Não há ambiente de testes (sandbox). Todo pedido gera uma cobrança real.
• Um tempo limite esgotado na consulta não significa que o pedido falhou. Procure o pedido pelo orderId ou clientOrderId antes de fazer um novo pedido.

Erros comuns

Os erros trazem code, requestId, message e, opcionalmente, detail.field. Trate-os pelo code; message vem em um de 9 idiomas conforme o Accept-Language e serve apenas para exibição.