# API Donc -- Guia de Integracao de Jobs

**Versao:** 3.0 -- Marco de 2026
**Area:** Desenvolvimento
**Tipo:** API REST -- Integracao de Jobs

## 01 -- Qual metodo usar?

A API Donc oferece dois endpoints para criacao de Jobs:

### Efetivacao Imediata -- SalvarValidandoCodigoDuplicado

- **Endpoint:** /api/JobsNovo/SalvarValidandoCodigoDuplicado
- O Job e criado e confirmado na mesma requisicao. A resposta ja retorna o Id.
- Use quando precisar do Id imediatamente.

### Processamento em Fila -- SalvarProcessamentoFila

- **Endpoint:** /api/JobsNovo/SalvarProcessamentoFila
- O Job e enfileirado e processado em background a cada 5 a 10 minutos.
- Ideal para alto volume ou integracoes assincronas.

| Caracteristica | SalvarValidandoCodigoDuplicado | SalvarProcessamentoFila |
|---------------|-------------------------------|------------------------|
| Processamento | Sincrono -- imediato | Assincrono -- fila de 5-10 min |
| Retorno em sucesso | "1042" (Id numerico) | {"status":"recebido",...} |
| Retorno em erro | HTTP 500 com JSON de erro | HTTP 500 com JSON de erro |
| Validacoes na entrada | CodigoJob + Cliente + Endereco completo + DataExecucao | Somente CodigoJob + Cliente.Nome + Cliente.Telefone |
| Verificacao de duplicidade | Na mesma chamada | No momento do processamento |
| JSON de entrada | Identico para ambos os metodos | Identico para ambos os metodos |

## 02 -- Agendamento com profissional

Em ambos os metodos, enviar o bloco Parceiro com profissional identificado cria o Job ja com agendamento automatico.

Para funcionar corretamente:
- Envie DataExecucao com a data e hora exatas
- Envie o bloco Parceiro com ao menos um campo de identificacao: Id, Telefone, Email ou CodigoManual
- O profissional deve estar cadastrado e ativo no sistema Donc

## 03 -- Obtendo o token (API Key)

O token e um GUID unico do seu estabelecimento. Autentica todas as requisicoes.

**Documentacao interativa -- Swagger:** `https://apiv2.donc.com.br/swagger/ui/index`

1. Acesse o Admin Donc
2. Navegue ate Setup -> Integracao -> API Key
3. Copie o token (GUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
4. Guarde com seguranca

> **ALERTA:** Tokens comprometidos -- entre em contato com o suporte Donc para regenerar imediatamente.

## 04 -- Configurando o header

Toda requisicao deve conter o token no header HTTP com a chave `apikey`.

```
POST https://apiv2.donc.com.br/api/JobsNovo/SalvarValidandoCodigoDuplicado HTTP/1.1
Content-Type: application/json
apikey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

- ERRADO: Usar Authorization: Bearer ... ou X-Api-Key: ... -- a chave deve ser exatamente `apikey` em letras minusculas.
- CORRETO: Header: `apikey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

> **ALERTA:** Token invalido ou ausente -- A API retorna HTTP 500 com ApiKeyRequired ou ApiKeyNotFound. Nao ha redirecionamento nem HTTP 401.

## 05 -- TipoJobId e FormaPagamentoId

Estes campos referenciam cadastros do seu ambiente Donc. Os Ids variam por contrato.

1. TipoJobId -- Acesse Admin -> Setup -> Tipos de Job
2. FormaPagamentoId -- Acesse Admin -> Setup -> Formas de Pagamento

Se omitidos, o sistema tenta usar os valores padrao cadastrados no contrato.

## 06 -- Identificacao do cliente

O sistema busca um cliente ja cadastrado na seguinte ordem de prioridade. Se encontrado, atualiza os dados. Se nao encontrado, cria novo cadastro automaticamente.

**OBRIGATORIO:** CPF, CNPJ ou Telefone. Enviar apenas Cliente.Nome nao e suficiente.

| Prioridade | Campo | Regras |
|-----------|-------|--------|
| 1 (mais alta) | Cliente.CPF | Aceita com ou sem pontuacao. Se maior que 11 digitos, trata como CNPJ. |
| 2 | Cliente.CNPJ | Aceita com ou sem pontuacao. |
| 3 | Cliente.Telefone | Somente digitos. Obrigatorio se CPF e CNPJ forem omitidos. |
| 4 (mais baixa) | Cliente.Email | Opcional. Se invalido ou ausente, sistema gera e-mail interno. |

**Recomendacao:** Envie sempre CPF ou CNPJ quando disponivel.

## 07 -- Campos obrigatorios

Exigidos por SalvarValidandoCodigoDuplicado. O metodo de fila exige apenas CodigoJob + Cliente.Nome + Cliente.Telefone na entrada.

| Campo | Tipo | Descricao |
|-------|------|-----------|
| CodigoJob | string | Codigo unico da OS no seu sistema. Previne duplicidade. |
| DataExecucao | datetime | Data de agendamento. Formato: 2025-06-10T08:00:00 |
| TipoJobId | int | Id do tipo de Job no Admin. Se omitido, usa padrao do contrato. |
| FormaPagamentoId | int | Id da forma de pagamento. Se omitido, usa padrao. |
| Cliente.Nome | string | Nome completo do cliente destinatario. |
| Cliente.Telefone | string | Telefone com DDD. Somente digitos. |
| Endereco.Logradouro | string | Rua/Avenida. Max 500 caracteres. |
| Endereco.Bairro | string | Bairro. Max 250 caracteres. |
| Endereco.Cidade | string | Cidade. Max 250 caracteres. |
| Endereco.Estado | string | UF com exatamente 2 caracteres. |
| Endereco.CEP | string | Max 8 digitos. Aceita com hifen. |

## 08 -- Campos opcionais

| Campo | Tipo | Descricao |
|-------|------|-----------|
| Descricao | string | Observacoes livres. |
| DataLimiteExecucao | datetime | Prazo maximo. Se omitido, assume DataExecucao. |
| DataPublicacao | datetime | Se omitida, assume DataExecucao. |
| DataExpiracao | datetime | Se omitida, assume DataExecucao + 7 dias. |
| Cliente.CPF | string | Recomendado. Identificacao primaria. |
| Cliente.CNPJ | string | Para PJ. |
| Cliente.Email | string | Opcional. |
| Endereco.Numero | string | Max 50 chars. Se omitido, assume S/N ou extrai do Logradouro. |
| Endereco.Complemento | string | Apto, bloco, sala. Max 250. |
| Endereco.Referencia | string | Ponto de referencia. Max 250. |
| ValorCobrar | decimal | Valor cobrado do cliente. |
| ValorPagar | decimal | Valor a pagar ao profissional. |
| Parceiro.Id | int | Id direto do parceiro. Prioridade maxima. |
| Parceiro.NomeFantasia | string | Usado para criar novo parceiro se nenhum for encontrado. |
| Parceiro.Telefone | string | Identificacao do parceiro. |
| Parceiro.Email | string | Identificacao alternativa. |
| Parceiro.CodigoManual | string | Codigo externo do parceiro. |
| Parceiro.Profissionais[].Id | int | Id do profissional para agendamento automatico. |
| Parceiro.Profissionais[].Telefone | string | Telefone para busca. |
| Parceiro.Profissionais[].Email | string | E-mail para busca. |
| Parceiro.Profissionais[].CodigoManual | string | Codigo externo do profissional. |

## 09 -- JSON minimo

```json
{
  "CodigoJob":        "OS-322345678",
  "DataExecucao":     "2026-03-10T08:00:00",
  "TipoJobId":        471,
  "FormaPagamentoId": 160,
  "Descricao":        "Entrega de produto - NF 4521",
  "Cliente": {
    "Nome":     "Maria Silva",
    "Telefone": "11111111111",
    "CPF":      "12312312388"
  },
  "Endereco": {
    "Logradouro":  "Rua das Flores",
    "Numero":      "100",
    "Complemento": "Apto 12",
    "Bairro":      "Centro",
    "Cidade":      "Florianopolis",
    "Estado":      "SC",
    "CEP":         "88010-000",
    "Referencia":  "Proximo ao mercado"
  }
}
```

## 10 -- JSON completo

```json
{
  "CodigoJob":           "OS-322345678",
  "DataExecucao":        "2026-03-10T08:00:00",
  "DataLimiteExecucao":  "2026-03-10T18:00:00",
  "DataPublicacao":      "2026-03-09T07:00:00",
  "DataExpiracao":       "2026-03-17T23:59:00",
  "TipoJobId":           471,
  "FormaPagamentoId":    160,
  "Descricao":           "Entrega de produto - NF 4521",
  "ValorCobrar":         150.00,
  "ValorPagar":          80.00,
  "Cliente": {
    "Nome":     "Maria Silva",
    "Telefone": "11111111111",
    "Email":    "maria.silva@email.com",
    "CPF":      "12312312388",
    "CNPJ":     ""
  },
  "Endereco": {
    "Logradouro":  "Rua das Flores",
    "Numero":      "100",
    "Complemento": "Apto 12",
    "Bairro":      "Centro",
    "Cidade":      "Florianopolis",
    "Estado":      "SC",
    "CEP":         "88010-000",
    "Referencia":  "Proximo ao mercado",
    "Latitude":    "-27.5954",
    "Longitude":   "-48.5480"
  },
  "Parceiro": {
    "Id":           0,
    "NomeFantasia": "Transportadora JS",
    "Telefone":     "48988887777",
    "Email":        "contato@transportadorajs.com.br",
    "CodigoManual": "PARC-001",
    "Profissionais": [
      {
        "Id":           0,
        "Telefone":     "48977776666",
        "Email":        "entregador@transportadorajs.com.br",
        "CodigoManual": "PROF-042"
      }
    ]
  }
}
```

## 11 -- Retornos possiveis

| Situacao | SalvarValidandoCodigoDuplicado | SalvarProcessamentoFila |
|----------|-------------------------------|------------------------|
| Sucesso | "1042" | {"status":"recebido","codigoJob":"OS-..."} |
| Job ja existe e ativo | "1042" (Id existente) | Processado na fila -- mesmo comportamento |
| Job existia Cancelado | "2089" (novo Job) | Processado na fila -- novo Job criado |
| Token invalido | HTTP 500 -- ApiKeyRequired / ApiKeyNotFound | idem |
| Campo obrigatorio ausente | HTTP 500 -- descricao do campo | HTTP 500 -- somente CodigoJob / Cliente |
| TipoJobId invalido | HTTP 500 -- "Tipo de Job nao existe" | Erro no processamento da fila |
| Parceiro nao vinculado | HTTP 500 -- PartnerNotAvaiableToPlace | idem |

## 12 -- Regras e observacoes

- **Identificacao obrigatoria do cliente** -- ao menos CPF, CNPJ ou Telefone. Integracoes apenas por Nome serao rejeitadas.
- **CodigoJob** -- use o identificador unico da OS no seu sistema. Previne duplicidade em ambos os metodos.
- **CPF/CNPJ** -- envie sempre que disponivel para garantir identificacao precisa.
- **Estado** -- deve ter exatamente 2 caracteres (UF). Valores maiores sao truncados.
- **CEP** -- max 8 digitos.
- **Agendamento** -- envie o bloco Parceiro com o profissional identificado e o Job sera agendado automaticamente na DataExecucao.
- **Fila** -- nao use se precisar do Id imediatamente.
- **Parceiro novo** -- se nenhum for encontrado e todos os campos forem enviados, o sistema cria automaticamente.
- **Numero S/N** -- se omitido, tenta extrair do Logradouro no formato "Rua X, 100", caso contrario assume S/N.

## 13 -- Servico de processamento da fila

Apos um Job ser inserido via SalvarProcessamentoFila, ele e consumido por um servico Windows em background.

**Servico responsavel:** ProcessaFilaIntegracaoContratoSaas-{id}

Este servico Windows consome a fila de integracao e processa cada Job enfileirado. Ele executa periodicamente a cada 5 a 10 minutos, aplicando as mesmas validacoes e regras de negocio do metodo imediato.

**Logs de execucao:** `F:\DoncLogs\LogsIntegracao\FilaIntegracao`

Os logs registram:
- Inicio e fim de cada ciclo de processamento
- Jobs processados com sucesso -- CodigoJob e Id gerado
- Jobs com erro -- mensagem detalhada do problema
- Jobs ignorados por duplicidade -- CodigoJob ja existente e ativo

**Depuracao -- Job nao apareceu apos 10 minutos:** Consulte os logs. Erros mais comuns: cliente sem CPF/CNPJ/Telefone, TipoJobId invalido e endereco incompleto.