Criar serviços

A sua integração pode criar um serviço da central com as peças já definidas no seu sistema. O Cortecloud cadastra o marceneiro, preenche as peças, envia o serviço para otimização e gera o orçamento, como num serviço criado pelo app.

Rota: POST /services. Exige autenticação por central (HMAC); com autenticação Basic, responde 401.

Corpo

{
  "serviceInternalCode": "PED-123",
  "productionInternalCode": "LINHA-1",
  "carpenterEmail": "marceneiro@example.com",
  "carpenterName": "Fulano Marceneiro",
  "carpenterInternalCode": "CLI-9",
  "parts": [
    {
      "quantity": 1,
      "c": 500,
      "l": 500,
      "function": "Lateral",
      "complement": "Balcao A",
      "client": "Ana",
      "furniture": "Cozinha",
      "material": { "internalCode": "MDF18BR" },
      "c1": { "internalCode": "FT04BR" },
      "c2": null,
      "l1": null,
      "l2": null,
      "machining": {
        "x": 500,
        "y": 500,
        "z": 18,
        "startSide": 0,
        "horizontalDrills": [],
        "verticalDrills": [
          { "corner": 0, "bolthole": false, "x": 25, "y": 37, "depth": 12, "diameter": 15, "face": "i" }
        ],
        "furrowMachining": null,
        "furrowMachiningPair": null
      }
    }
  ]
}

Campo	Regra
`serviceInternalCode`	Código interno do serviço, normalmente o número do pedido no ERP. Opcional, até 255 caracteres. Volta nos webhooks como `service_internal_code`.
`productionInternalCode`	Código interno da linha de produção. Obrigatório.
`carpenterEmail`, `carpenterName`	E-mail e nome do marceneiro. Obrigatórios.
`carpenterInternalCode`	Código do marceneiro (cliente) no seu sistema. Obrigatório.
`parts`	Peças do serviço, de 1 a 500.

Antes de criar o serviço, a rota cadastra o marceneiro no Cortecloud, caso ainda não exista, e o vincula à central com carpenterInternalCode, como no login embutido. Se o marceneiro já tem vínculo ativo com a central, o código interno desse vínculo é mantido. Se carpenterEmail já pertence a um usuário de outro perfil (por exemplo, um vendedor), ele passa a ser marceneiro e perde o perfil anterior.

Peças

parts segue a estrutura da importação por arquivo JSON: os mesmos campos, as medidas em milímetros e o mesmo objeto machining, descrito em Usinagem. As diferenças estão nos materiais e na validação:

Campo	Na importação	Aqui
`material`	Nome da chapa no seu sistema.	Chapa da peça: `{ "internalCode": "..." }`, com o código interno da chapa na central. Obrigatório.
`client`, `furniture`	Não existem: o marceneiro escolhe o cliente na importação.	Cliente do marceneiro e ambiente da peça (por exemplo, "Cozinha"), até 255 caracteres cada. Opcionais: peças com o mesmo par ficam no mesmo cliente do serviço, e as peças sem eles ficam num cliente sem nome.
`c1`, `c2`, `l1`, `l2`	Nome da fita.	`{ "internalCode": "..." }` com o código interno da fita na central. Lado sem fita: `null` ou ausente.
`quantity`, `c`, `l`	A peça com valor ausente, zero ou negativo é descartada.	Valor ausente, zero ou negativo responde `400`. `c` e `l` vão até 9999.99.

Os códigos internos de chapa e fita, function e complement têm até 255 caracteres; acima disso, a rota responde 400.

Como os materiais chegam pelo código interno, não existe a etapa de vínculo de materiais da importação.

Valem as mesmas regras da importação:

function vazio vira "Peça".
A usinagem só é aplicada se a linha de produção tiver máquina de usinagem (ver Quando a linha de produção não usina).
Cada peça usa no máximo duas fitas diferentes. Se a central não aceita duas fitas por peça, os lados com a segunda fita ficam sem fita.

Não há campo para a rotação da peça: ela pode girar no plano de corte quando a chapa não tem veio.

Resposta e acompanhamento

A resposta 202 traz o id do serviço:

{ "id": 98765 }

O 202 confirma o formato do corpo e o cadastro do marceneiro. Materiais, linha de produção e peças são validados depois, de forma assíncrona: um código de chapa inexistente, por exemplo, não muda a resposta. O resultado chega por webhook:

service.created: o serviço foi criado e as peças foram gravadas (status 1);
service.creation_failed: a criação falhou, e errors traz os motivos.

O service.created sai depois que o serviço é enviado para otimização. Quando o orçamento fica pronto, chega o service.quoted. Se o envio for recusado, por exemplo por uma peça maior que a chapa, chega service.creation_failed com os motivos. Para receber os três, peça o cadastro de destinos para cada tipo (ver Como ativar).

Enquanto o Cortecloud preenche as peças, o serviço fica bloqueado para edição nos apps.

Ids das peças

O orçamento e as peças ficam em GET /services/{id}. parts[].id é o id de cada peça no Cortecloud: use-o para correlacionar as peças com o seu sistema, por exemplo com o DrillCode das usinagens.

O que o marceneiro vê

O serviço pertence à central e fica associado ao marceneiro. Ele aparece no Cortecloud do marceneiro a partir do status aprovado (6), só para leitura.

Erros

Status	Quando
`400`	Corpo fora do formato: campo obrigatório ausente, e-mail inválido, `parts` vazio ou com mais de 500 peças, peça sem `material`, quantidade ou medida não positiva, `machining` fora do formato da importação.
`401`	Autenticação Basic. A rota exige HMAC.

Erros nos materiais, na linha de produção ou nas peças, inclusive peça maior que a chapa, chegam pelo service.creation_failed, não na resposta.

Nova tentativa depois de timeout

serviceInternalCode não passa por checagem de duplicidade. Se a resposta se perder e a sua integração repetir a chamada, o Cortecloud pode criar o serviço duas vezes.

Corpo​

Peças​

Resposta e acompanhamento​

Ids das peças​

O que o marceneiro vê​

Erros​