JOVPay Protestos

Como funciona

1. Autentique sua empresa com a chave privada JOVPay no backend.
2. Use o cliente já cadastrado na mesma empresa (customer_id) ao importar uma fatura externa.
3. Crie o dossiê em POST /api/v1/protests, informando source_type e os campos da origem.
4. Guarde o ID do dossiê retornado e evite criar registros duplicados.
5. Anexe a fatura externa original e os documentos existentes, usando multipart/form-data.
6. Confira o dossiê no painel da JOVPay; status ready significa somente conferência interna.
7. Consulte GET /api/v1/protests/{id}/readiness para verificar pendências sem enviar o título.

Origem da solicitação

source_type aceita charge (identificada por public_token), pix_automatic_billing (identificada por billing_id e opcionalmente schedule_id) ou external_invoice (fatura do seu sistema, com referência própria, customer_id, valor, vencimento, descrição e payment_status = unpaid). Em faturas externas, a JOVPay não consegue confirmar automaticamente a inadimplência informada pelo integrador.

Criar um rascunho via API

Exemplo ilustrativo de criação de dossiê a partir de uma fatura vencida. Todos os dados abaixo são fictícios. O token deve ficar somente no servidor.

curl -X POST "https://jovpay.com/api/v1/protests" \
  -H "Authorization: Bearer SEU_TOKEN_JOVPAY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "external_invoice",
    "external_system": "erp",
    "external_reference": "FAT-2026-101",
    "customer_id": 42,
    "amount": 317.00,
    "due_date": "2026-10-05",
    "description": "Serviço contratado - competência setembro",
    "payment_status": "unpaid"
  }'

Anexar a fatura original

O arquivo permanece em armazenamento privado. Para faturas externas, a fatura original deve ser anexada como invoice antes da conferência.

curl -X POST "https://jovpay.com/api/v1/protests/101/documents" \
  -H "Authorization: Bearer SEU_TOKEN_JOVPAY" \
  -H "Accept: application/json" \
  -F "evidence_type=invoice" \
  -F "file=@/caminho/fatura.pdf"

Consultar a preparação

A consulta readiness retorna pendências e a disponibilidade do envio. Ela não transmite documentos, não cria protocolos e não altera cobranças.

curl "https://jovpay.com/api/v1/protests/101/readiness" \
  -H "Authorization: Bearer SEU_TOKEN_JOVPAY" \
  -H "Accept: application/json"

Estados e proteção dos títulos

1. draft — dossiê ainda em preparação e sujeito às validações do serviço.
2. ready — conferência interna concluída; dossiê bloqueado para edição.
3. submitted = false e can_submit = false — ainda não há transmissão de títulos disponível.
4. Quando um título estiver conferido, as operações protegidas de pagamento, edição e exclusão permanecem bloqueadas de acordo com as regras da JOVPay.
5. Não interprete ready, recebido ou consulta como protesto registrado.

Receber atualizações por webhook

Em Integrações > Webhook, configure uma URL HTTPS e marque explicitamente quais eventos de Protestos quer receber. A seleção vazia não ativa webhooks deste produto. A entrega é enfileirada após a confirmação do registro e pode ser repetida. Deduplicate por event_id; o header X-JOV-Event-Id possui o mesmo valor.

Eventos de dossiê disponíveis

1. protest.created — novo dossiê interno criado.
2. protest.updated — rascunho atualizado.
3. protest.document_added — um anexo foi incluído, sem enviar o arquivo no webhook.
4. protest.documents_confirmed — etapa de documentos confirmada.
5. protest.ready — conferência interna concluída, sem protocolo externo.
6. Eventos de apresentação, andamento e desfecho só serão disponibilizados após integração e homologação oficial.