# Guia Rápido de Consumo para o `app.vcnodigital.com` Base: - `https://icms.vcnodigital.com` Autenticação: - `Authorization: Bearer ` Objetivo: - dar ao time do `app.vcnodigital.com` um fluxo de consumo curto, previsível e sem mistura entre empresas, parcelas ou versões de artefato ## 1. Chaves que o app deve respeitar Chave preferida: - `guideId + documentType` Fallback seguro: - `companyId + numeroDocumento + parcela + documentType` Fallback de compatibilidade: - `company.cnpj + numeroDocumento + parcela + documentType` Nunca usar sozinho: - `numeroDocumento` Motivo: - o mesmo número pode existir em empresas diferentes - o mesmo número pode existir em parcelas diferentes - o mesmo número pode voltar com novo `artifactId` após reemissão ou `force-republish` ## 2. Fluxo mínimo de integração ### Passo A. Bootstrap do cursor Uma vez por controladora: ```bash curl -H "Authorization: Bearer " \ "https://icms.vcnodigital.com/api/internal/fiscal-documents/upload-events?bootstrap=1" ``` Guardar: - `cursor` ### Passo B. Polling leve de eventos Rodar a cada `15-30s`: ```bash curl -H "Authorization: Bearer " \ "https://icms.vcnodigital.com/api/internal/fiscal-documents/upload-events?after_id=&ready_only=1&limit=30" ``` Quando agir: - se vier evento com `readyForVitrine = true` - se vier `documentsHint` com `dare` ou `extrato_dare` Não baixar PDF direto do evento: - o evento é gatilho - a fonte final continua sendo `GET /api/internal/fiscal-documents` ### Passo C. Buscar documentos prontos Sincronização principal: ```bash curl -H "Authorization: Bearer " \ "https://icms.vcnodigital.com/api/internal/fiscal-documents?pending_only=1" ``` Filtros úteis: - `cnpj` - `numeroDocumento` - `parcela` - `pending_delivery_only=1` - `delivery_status` - `includeAuditArtifacts=1` apenas para suporte/auditoria ### Passo D. Persistir no app Para cada item retornado: - iterar em `documents[]` - montar chave operacional por `guideId + documentType` ou fallback seguro - salvar `artifactId`, `fileName`, `downloadUrl`, `viewerUrl`, `dueDate`, `vencimentoOriginal`, `vencimentoEmitido`, `recalculada`, `workflowStatus` e `delivery.*` - marcar como substituição quando a mesma chave voltar com `artifactId` novo ### Passo E. Baixar e importar Regras: - consumir `documents[]` como fonte de documento final - ignorar `auditArtifacts[]` no fluxo normal - `extrato_dare` só deve entrar como documento cliente quando vier em `documents[]` ### Passo F. Confirmar importação Depois que o app importar o artefato com sucesso: ```bash curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"artifactId":140,"externalDocUrl":"https://app.vcnodigital.com/documentos/140"}' \ "https://icms.vcnodigital.com/api/internal/fiscal-documents/mark-exported" ``` ### Passo G. Confirmar entrega ao cliente Somente depois do envio real ao cliente: ```bash curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"artifactId":140,"deliveryStatus":"ENVIADO_CLIENTE","channel":"whatsapp","recipient":"5592999999999","messageId":"wamid...","ticketId":"4831"}' \ "https://icms.vcnodigital.com/api/internal/fiscal-documents/mark-delivered" ``` `deliveryStatus` aceitos: - `ENVIADO_CLIENTE` - `FALHA_ENTREGA` - `PENDENTE_REENVIO` ## 3. Como interpretar o retorno ### Documento parcial vs completo Se `documents[]` vier só com `dare`: - a guia já pode entrar na vitrine - o extrato separado ainda não está pronto ou não é exigível Se `extratoMode = embedded_in_dare`: - não esperar `extrato_dare` - o próprio DARE já é suficiente Se `documents[]` vier com `dare` e `extrato_dare`: - tratar como pacote completo com extrato separado Se existir só extrato no backoffice: - ele não deve sair em `documents[]` - permanece apenas para auditoria interna ### Campos de vencimento Consumir como principal: - `dueDate` - `dueDateReal` Consumir como histórico: - `vencimentoOriginal` - `vencimentoEmitido` Lógica: - se `recalculada = false`, o vencimento operacional é o original - se `recalculada = true`, o vencimento operacional é o emitido ### Campos de pareamento Campos úteis: - `pairing.guiaDisponivel` - `pairing.extratoDisponivel` - `pairing.extratoEsperado` - `pairing.extratoNaoExigivel` - `pairing.guiaCompletaParaCliente` Uso: - o app pode considerar o card pronto quando `pairing.guiaCompletaParaCliente = true` ## 4. Quando o app deve pedir nova emissão Antes de abrir job: ```bash curl -H "Authorization: Bearer " \ "https://icms.vcnodigital.com/api/internal/fiscal-documents/due-options?numeroDocumento=20261600483103&parcela=00&only_with_available_dates=1" ``` Abrir job somente se: - a data desejada estiver dentro de `availableDueDates[]` - o documento realmente precisar ser reemitido Criar job pontual: ```bash curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"controladoraId":1,"commandType":"fetch_numero_documento","companyId":97,"cnpj":"0000006559719","numeroDocumento":"20261600483103","parcela":"00","year":2026,"targetDueDate":"2026-03-31","consumeAvailableDueDates":true,"force":true,"requestedBy":"VC Digital"}' \ "https://icms.vcnodigital.com/api/internal/orchestrator/jobs" ``` Acompanhar: ```bash curl -H "Authorization: Bearer " \ "https://icms.vcnodigital.com/api/internal/orchestrator/jobs?numeroDocumento=20261600483103&parcela=00&limit=20" ``` ## 5. Quando o app deve substituir documento antigo Substituir imediatamente quando: - a mesma chave operacional voltar com `artifactId` novo - houver `force-republish` - houver reemissão com novo PDF final Não manter os dois como ativos: - o app deve preservar histórico interno se quiser - mas a vitrine e o documento vigente precisam apontar para o `artifactId` mais novo ## 6. Como reagir a pagamento inferido Consumir: ```bash curl -H "Authorization: Bearer " \ "https://icms.vcnodigital.com/api/internal/fiscal-documents/payment-events?after_id=&limit=30" ``` Ao receber `SEFIN_PAYMENT_INFERRED`: - localizar a guia pela chave operacional - tirar da vitrine de pendentes - mover para histórico com motivo `paid` ## 7. O que não fazer - não deduplicar por `numeroDocumento` sozinho - não tratar `auditArtifacts[]` como documento final - não chamar `mark-exported` antes da importação real - não chamar `mark-delivered` antes do envio real ao cliente - não assumir que `extrato_*` sozinho já libera o documento na vitrine - não abrir reemissão sem antes consultar `due-options` ## 8. Checklist de homologação - bootstrap de cursor por controladora funcionando - polling de `upload-events` funcionando - importação de `documents[]` funcionando - substituição por `artifactId` novo funcionando - `mark-exported` gravando retorno no ICMS - `mark-delivered` gravando retorno no ICMS - baixa por `payment-events` tirando guia da vitrine - filtro por `cnpj` e por `numeroDocumento + parcela` funcionando ## 9. Arquivos de apoio - `GET /docs/vc-digital.md` - `GET /docs/vc-digital-curl-examples.txt` - `GET /docs/vc-digital-example-response.json` - `GET /docs/vc-digital-due-options-example.json` - `GET /docs/vc-digital-mark-exported-example.json` - `GET /docs/vc-digital-mark-delivered-example.json` - `GET /docs/vc-digital-error-catalog.json`