Autenticação

Enviar Authorization: Bearer <token da controladora> em todas as requisições. O token limita o acesso à carteira da própria controladora.

Arquivos para o outro programador

Consumo incremental

Fila prioritária WNS

Para homologação inicial, a recomendação é consumir primeiro as empresas com mais DAREs já capturados e com maior cobertura de artefatos úteis.

Endpoints

Reenvio compulsório de manutenção

Use esse fluxo quando o VC Digital já tiver importado um PDF antigo/errado e precisar substituir o documento sem depender de reset local do outro lado.

curl -X POST
  -H "Authorization: Bearer <token-da-controladora>"
  -H "Content-Type: application/json"
  -d '{
    "controladoraId": "2",
    "companyId": 3,
    "numeroDocumento": "20261200047276"
  }'
  "https://icms.vcnodigital.com/api/internal/fiscal-documents/force-republish"

Configuração esperada no VC Digital

Para a primeira conexão, o outro sistema deve ativar o módulo fiscal da empresa, usar a base do ICMS SaaS e informar o identificador da controladora selecionada abaixo.

fiscalApiEnabled = true
fiscalApiBaseUrl = "https://icms.vcnodigital.com"
fiscalApiKey = "<token-da-controladora>"
fiscalApiSubdomain = ""
fiscalApiImportPath = ""
fiscalApiExtraFields = {
  "controladoraId": "2",
  "markExportedPath": "/api/internal/fiscal-documents/mark-exported",
  "markDeliveredPath": "/api/internal/fiscal-documents/mark-delivered",
  "markExportedAfterImport": true
}

Se o backend do VC Digital já assumir o padrão /api/internal/fiscal-documents, o campo fiscalApiImportPath pode ficar vazio no primeiro teste.

Autenticação e headers

Consulta principal

Com token de controladora, o filtro de carteira já é aplicado automaticamente. Use cnpj e/ou numeroDocumento para refinar.

curl -H "Authorization: Bearer <token-da-controladora>" "https://icms.vcnodigital.com/api/internal/fiscal-documents?cnpj=60789911000171&pending_only=1"

curl -H "Authorization: Bearer <token-da-controladora>" "https://icms.vcnodigital.com/api/internal/fiscal-documents?cnpj=60789911000171&pending_only=1&includeAuditArtifacts=1"

Campos entregues por documento

Tipos de documento expostos hoje

Semântica de vencimento

Regra operacional: se a guia não foi recalculada, o consumo deve seguir vencimentoOriginal. Se foi recalculada, o consumo deve seguir vencimentoEmitido.

Resposta

{
  "error": false,
  "total": 1,
  "data": [
    {
      "guideId": 123,
      "company": {
        "id": 45,
        "cnpj": "60789911000171",
        "inscricaoEstadual": "0000000000000",
        "razaoSocial": "F DOS REIS SANTOS"
      },
      "controladora": {
        "id": 1,
        "nome": "Wns contabilidade",
        "companyId": "vc-company-001"
      },
      "numeroDocumento": "20261100080905",
      "parcela": "00",
      "dueDate": "2026-03-15",
      "dueDateReal": "2026-03-15",
      "dueDateSource": "LISTA_SEFIN",
      "vencimentoOriginal": "2026-03-15",
      "vencimentoEmitido": "2026-03-15",
      "valorTotal": "86.47",
      "externalIds": {
        "dare": "dare-20261100080905",
        "extrato": "extrato-20261100080905"
      },
      "recalculada": false,
      "documents": [
        {
          "documentType": "dare",
          "externalId": "dare-20261100080905",
          "title": "DARE Administrativo",
          "dueDate": "2026-03-15",
          "dueDateReal": "2026-03-15",
          "dueDateSource": "LISTA_SEFIN",
          "vencimentoOriginal": "2026-03-15",
          "vencimentoEmitido": "2026-03-15",
          "cnpj": "60789911000171",
          "numeroDocumento": "20261100080905",
          "downloadUrl": "https://icms.vcnodigital.com/artifact/view?id=140"
        },
        {
          "documentType": "extrato_dare",
          "externalId": "extrato-20261100080905",
          "title": "Extrato DARE",
          "dueDate": "2026-03-15",
          "dueDateReal": "2026-03-15",
          "dueDateSource": "LISTA_SEFIN",
          "vencimentoOriginal": "2026-03-15",
          "vencimentoEmitido": "2026-03-15",
          "cnpj": "60789911000171",
          "numeroDocumento": "20261100080905",
          "downloadUrl": "https://icms.vcnodigital.com/artifact/view?id=141"
        }
      ],
      "dare": {
        "available": true,
        "artifactId": 140,
        "downloadUrl": "https://icms.vcnodigital.com/artifact/view?id=140",
        "viewerUrl": "https://docs.google.com/gview?embedded=1&url=..."
      },
      "extrato": {
        "available": true,
        "artifactId": 141,
        "downloadUrl": "https://icms.vcnodigital.com/artifact/view?id=141"
      }
    }
  ]
}

Marcar exportado

curl -X POST \
  -H "Authorization: Bearer <token-da-controladora>" \
  -H "Content-Type: application/json" \
  -d '{"artifactId":140,"externalDocUrl":"https://doc.vcnodigital.com/documentos/abc"}' \
  "https://icms.vcnodigital.com/api/internal/fiscal-documents/mark-exported"

Arquivos

Modo opcional de auditoria

O VC Digital deve tratar auditArtifacts[] como apoio interno. Documento fiscal final para cliente continua sendo PDF do DARE e PDF do extrato; os snapshots SEFIN são artefatos de apoio e não substituem o documento final.

Erros e consistência