# Manual de integração do Parceiro

***

## **Objetivos da integração**

* Automatizar o lançamento de pedidos no sistema PDV
* Permitir a emissão de documentos fiscais pelo sistema PDV
* Unificar o processo operacional dos estabelecimentos
* Unificar relatórios

***

## **Fluxo**

![Fluxo de integração](/files/-MDLZ9J1CvSOSdj2rqNs)

***

## **Acesso a API (Versão 2)**

**Endereço:** [https://api.ccmpedidoonline.com.br/wsccm\_v2.php](http://api.ccmpedidoonline.com.br/wsccm.php)

**Parâmetros de entrada HTTP GET**

| Nome             | Tipo          | Descrição                                                                                                                                                                                                                                                                                |
| ---------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **token \***     | Texto(25)     | Token de acesso obrigatório em todas as requisições.                                                                                                                                                                                                                                     |
| **import**       | Inteiro       | Número do pedido que não deverá ser listado novamente **(marca o pedido como importado – Efetuar esta chamada quando o sistema conseguiu importar um pedido com sucesso)**                                                                                                               |
| **getnropedido** | Inteiro       | Número do pedido a ser listado **(utilizar somente se precisar consultar um pedido já marcado como importado)**                                                                                                                                                                          |
| ~~**format**~~   | ~~Texto(10~~) | ~~Formato da saída dos dados “xml” ou “json” Este parâmetro é opcional, pois por padrão qualquer saída será formatada em XML (Descontinuado na versão 1.5 – Por questões de compatibilidade a implementação ainda existe na API, mas não recomendamos a utilização em novos projetos).~~ |

**Informações Importantes** 

* Toda requisição deverá acompanhar o parâmetro token
* Os parâmetros de entrada são **case sensitive**
* O separador decimal de todos os campos monetários é “.” (ponto)

***

### Cabeçalho do pedido

> **XML DE RETORNO**

<table data-header-hidden><thead><tr><th>Campo</th><th>Tipo</th><th width="200">Descrição</th><th>Exemplo</th></tr></thead><tbody><tr><td><strong>Campo</strong></td><td>Tipo</td><td>Descrição</td><td>Exemplo</td></tr><tr><td><strong>nroPedido</strong></td><td>Inteiro</td><td>Número do pedido no sistema CCM</td><td>1</td></tr><tr><td><strong>retira</strong></td><td>Inteiro</td><td>0 = Pedido delivery <br>1 = Pedido retirada balcão</td><td>0</td></tr><tr><td><strong>ValorTotal</strong></td><td>Moeda</td><td>Valor total do pedido incluindo a taxa de entrega</td><td>2.50</td></tr><tr><td><strong>ValorTaxa</strong></td><td>Moeda</td><td>Valor da taxa de entrega</td><td>1.00</td></tr><tr><td><strong>TrocoPara</strong></td><td>Moeda</td><td>Troco solicitado no pedido</td><td>100.00</td></tr><tr><td><strong>CodPdvPagamento</strong></td><td>Inteiro</td><td>Código do tipo de pagamento no sistema PDV. Este campo possuí o valor 0 para tipo de pagamento dinheiro</td><td>0</td></tr><tr><td><strong>DescricaoPagamento</strong></td><td>Texto (80)</td><td>Descrição do tipo de pagamento utilizado</td><td>DINHEIRO</td></tr><tr><td><strong>ObsGeraisPedido</strong></td><td>Texto (80)</td><td>Observações gerais inclusas na finalização do pedido</td><td>Deixar com o porteiro</td></tr><tr><td><strong>CodigoFilial</strong></td><td>Inteiro</td><td>Número da loja no sistema CCM. Este campo só é utilizado em integração múltiplas lojas</td><td>1</td></tr><tr><td><strong>StatusPedido</strong></td><td>Texto(25)</td><td>Situação do pedido “<strong>Pedido Aceito</strong>”, “<strong>Pedido Recusado</strong>” e “<strong>Aguardando</strong>”. A integração somente deve capturar os pedidos aceitos pelo Agente CCM Pedidos.</td><td>Pedido Aceito</td></tr><tr><td><strong>DataHoraPedido</strong></td><td>DateTime</td><td>Data e hora que o pedido foi lançado no sistema CCM. Formato: <strong>YYYY-MMDD</strong> <strong>HH-MM-SS</strong></td><td>2016-04-27 10:43:28</td></tr><tr><td><strong>PedidoCPF</strong></td><td>Texto(14)</td><td>Documento CPF do cliente que fez o pedido (este campo não é obrigatório, portanto pode vir em branco).</td><td>11122233300</td></tr><tr><td><strong>OrigemPedido</strong></td><td>Texto(50)</td><td>“<strong>ANDROID</strong>”, “<strong>IPHONE</strong>” ou “<strong>SITE</strong>”. Origem do pedido.</td><td>SITE</td></tr><tr><td><del><strong>travaPedido</strong></del></td><td><del>Inteiro</del></td><td><del>0 ou 1. Se marcado como 1 o pedido precisa ser revisado na plataforma CCM para maior segurança. Uma boa pratica é implementar uma grande mensagem de aviso no Sistema PDV.</del></td><td><del>0</del></td></tr><tr><td><del><strong>travaMotivo</strong></del></td><td><del>Texto(255)</del></td><td><del>Motivo da trava, pode ser exibido na mensagem. Nada impede que o pedido seja importado, mas é recomendada a intervenção do operador para revisar o pedido.</del></td><td><del>Brindes no pedido – Revisão manual do operador do caixa</del></td></tr><tr><td><strong>StatusAcompanhamento</strong></td><td>Texto(14)</td><td>Status de acompanhamento do pedido. “<strong>Despachado</strong>”, “<strong>Em preparo</strong>”, “<strong>Saiu para entrega</strong>”, “<strong>Finalizado</strong>”, ou “<strong>Recusado</strong>”. Esta informação é somente para leitura <strong>(exceto Saiu para entrega e Finalizado, ver página sobre mudança de status de acompanhamento)</strong>. Considere “<strong>Saiu para entrega</strong>” no pedido retirada como pedido pronta para ser retirado.</td><td>Despachado</td></tr><tr><td><strong>HorarioRetirada</strong></td><td>Texto(100)</td><td>Horário para ir buscar o pedido no balcão (caso houver).</td><td>Entre 20:00 e 21:00</td></tr><tr><td><strong>NumeroMesa</strong></td><td>Inteiro</td><td>Preenchido nos pedidos que devem ser entregues direto na mesa. Nota: Pedido Mesa também tem o campo "retira" = 1.</td><td>1</td></tr><tr><td><strong>CreditoUtilizado</strong></td><td>Moeda</td><td>Saldo de créditos utilizado no pedido. Valor a Cobrar = (Valor Pedido - Credito Utilizado)</td><td>0.35</td></tr><tr><td><strong>ValorBruto</strong></td><td>Moeda</td><td>Valor da soma dos itens sem nenhum desconto aplicado. Desconto pode ser obtido através de (ValorTotal - ValorBruto).</td><td>1.00</td></tr><tr><td><strong>CupomDesconto</strong></td><td>Texto(30)</td><td>Código do Cupom de desconto utilizado no pedido, ou tag vazia se não houver nenhum cupom.</td><td>NATAL10</td></tr><tr><td><strong>ValorCupom</strong></td><td>Moeda</td><td>Valor do Cupom de desconto utilizado no pedido, ou 0.00 se não houver nenhum cupom.</td><td>1.00</td></tr><tr><td><strong>Debug</strong></td><td>Texto</td><td>Informações de diagnóstico, para identificar problemas na integração.</td><td>Produto apagado 133 - X BACON;</td></tr><tr><td><strong>Agendamento</strong></td><td>Inteiro</td><td>1 para pedido com agendamento e 0 para pedido comum.</td><td>1</td></tr><tr><td><strong>DataAgendamento</strong></td><td>Texto(20)</td><td>Data do agendamento.</td><td>Ter 24/04</td></tr><tr><td><strong>HoraAgendamento</strong></td><td>Texto(20)</td><td>Hora do agendamento.</td><td>09:00</td></tr><tr><td><strong>DataHoraAgendamento</strong></td><td>DateTime</td><td>Data/Hora do agendamento no formato YYYY-MM-DD HH:MM:SS</td><td>2022-01-01 13:00:00</td></tr><tr><td><strong>PagamentoOnline</strong></td><td>Inteiro</td><td>1 para pedidos que já foram pagos online, como cartão de crédito ou Pix e 0 para pagamento manual na entrega.</td><td>1</td></tr><tr><td><strong>PedidoIntegrado</strong></td><td>Inteiro</td><td>Flag de identificação se o pedido já foi ou não importado para o sistema PDV. Útil para evitar duplicidade de importação.</td><td>1</td></tr><tr><td><strong>cliente</strong></td><td>Cliente</td><td>Objeto com os dados do cliente</td><td>Não se aplica</td></tr><tr><td><strong>endereco</strong></td><td>Endereco</td><td>Objeto com o endereço utilizado para entrega</td><td>Não se aplica</td></tr><tr><td><strong>itens</strong></td><td>Lista</td><td>Lista de itens inclusos no pedido</td><td>Não se aplica</td></tr></tbody></table>

### Cliente

Todos os pedidos são autenticados, portando os dados do cliente sempre estarão preenchidos.

> **XML DE RETORNO**

| Campo           | Tipo      | Descrição                                                                                                        | Exemplo             |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | ------------------- |
| **codigo**      | Inteiro   | Código de identificação no sistema CCM                                                                           | 1                   |
| **nome**        | Texto(80) | Nome completo do cliente                                                                                         | João da Silva       |
| **telefone**    | Texto(80) | Telefone do cliente                                                                                              | 11911111111         |
| **email**       | Texto(80) | E-mail do cliente                                                                                                | <nome@provedor.com> |
| **FaceCliente** | Texto(80) | ID Facebook do cliente (Se disponível). Para baixar a foto do perfil use o link graph.facebook.com/v3.0//picture | 4                   |

### Endereço

Exceto para pedidos balcão (retira = 1) todos os outros possuem os dados do endereço de entrega.

> **XML DE RETORNO**

| **Campo**       | **Tipo**  | **Descrição**                                                                                          | **Exemplo**    |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------ | -------------- |
| **rua**         | Texto(80) | Rua                                                                                                    | Dr Tobias Lima |
| **numero**      | Texto(80) | Número                                                                                                 | 1493           |
| **complemento** | Texto(80) | Complemento                                                                                            | Sala 2         |
| **referencia**  | Texto(80) | Ponto de referência. *Este campo é opcional no sistema CCM*                                            | Pc Vitória     |
| **Bairro**      | Texto(80) | Nome do bairro                                                                                         | Centro         |
| **cidade**      | Texto(80) | Cidade                                                                                                 | São Paulo      |
| **estado**      | Texto(2)  | UF com 2 dígitos                                                                                       | SP             |
| **cep**         | Texto(15) | CEP (somente números) se estiver disponível. *Note que o CEP pode ser obrigatório a critério da loja.* | 14701100       |

### Item

Os itens são os produtos do sistema PDV vinculados através do CodPdv.

> **XML DE RETORNO**

| **Campo**       | Tipo              | Descrição                                                                                                                                                            | Exemplo          |
| --------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| **Codigo**      | Inteiro           | Código de registro do item no sistema CCM                                                                                                                            | 1                |
| **CodPdv**      | Inteiro           | Código do produto no sistema PDV                                                                                                                                     | 1                |
| **CodPdvGrupo** | Inteiro           | Código do grupo no sistema PDV. Este campo é utilizado para controlar tamanho de produtos.                                                                           | 1                |
| **Descricao**   | Texto(80)         | Descrição do produto no sistema CCM                                                                                                                                  | COCA COLA 2L     |
| **Quantidade**  | Inteiro           | Quantidade                                                                                                                                                           | 1                |
| **ValorUnit**   | Moeda             | Valor unitário praticado                                                                                                                                             | 5.00             |
| **ObsItem**     | Texto(80)         | Observações incluídas no item ao fazer o pedido.                                                                                                                     | Não muito gelada |
| **adicionais**  | *Lista Adicional* | Lista de adicionais do item                                                                                                                                          | Não se aplica    |
| **partes**      | *Lista Parte*     | Lista de partes quando o item é uma montagem. Este campo não é definido quando o item não é uma montagem. Exemplo, montagem de pizzas ou pratos com mais de um sabor | Não se aplica    |

### Adicional

Os adicionais são produtos no sistema PDV, vinculados através do CodPdv.

> **XML DE RETORNO**

| Campo          | Tipo      | Descrição                                      | Exemplo        |
| -------------- | --------- | ---------------------------------------------- | -------------- |
| **Codigo**     | Inteiro   | Código de registro do adicional no sistema CCM | 1              |
| **CodPdv**     | Inteiro   | Código do produto no sistema PDV               | 50             |
| **Descricao**  | Texto(80) | Descrição do produto no sistema CCM            | Bacon em dobro |
| **Quantidade** | Inteiro   | Quantidade                                     | 2              |
| **ValorUnit**  | Moeda     | Valor unitário praticado                       | 2.50           |

### Parte

As partes são produtos no sistema **PDV**, vinculados através do **CodPdvItem*****.***

Este nó só é preenchido para itens de montagem, por exemplo Pizza de três sabores, neste caso 3 nós  serão criados para especificar a observação e o código **PDV** dos produtos.                                            <br>

> ***Note que o código PDV do  deve ser ignorado nestes casos quando houver ao menos um nó .***

> **XML DE RETORNO**

| **Campo**       | Tipo      | Descrição                                                                                 | Exemplo    |
| --------------- | --------- | ----------------------------------------------------------------------------------------- | ---------- |
| **CodPdvItem**  | Inteiro   | Código de registro do item no sistema CCM                                                 | 1          |
| **ObsParte**    | Texto(80) | Observações especificas da parte                                                          | Sem Cebola |
| **CodPdvGrupo** | Inteiro   | Código do grupo no sistema PDV. Este campo é utilizado para controlar tamanho de produtos | 50         |

## Manter Loja Aberta (PING)

{% hint style="info" %}
Note que esta implementação pode ser ignorada caso opte em manter o programa CCM Pedidos visível para o usuário.
{% endhint %}

Para manter a loja disponível é necessário fazer uma chamada de API a cada **30 segundos** a fim de garantir que o estabelecimento está com a conexão de internet funcionando. Veja a seguir as duas formas de trabalhar com a requisição ping.

Para a função **PassivePing** o campo “**primeiraVerificacao**” deve ser preenchido como 1 na primeira execução da chamada, isto permite que a plataforma defina se a loja está ou não dentro do horário de funcionamento.

| Função          | Descrição                                                                                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **passivePing** | A loja só fica disponível se estiver dentro do horário de funcionamento configurado no CCM Retaguarda. Todas as regras de horário são respeitadas, inclusive múltiplos turnos. |
| **activePing**  | A loja sempre fica disponível para pedidos, desta forma o sistema PDV deve controlar quando o aplicativo está ou não disponível.                                               |

**Chamada**

```
wsccm.php?token=<SEUTOKEN> &funcao=passivePing &codFilial=1&primeiraVerificacao=0
```

**Retorno**

```
{"resultado":"ok","mensagem":"Loja fechada"}
```

```
{"resultado":"ok","mensagem":"Loja aberta"}
```

## Status do pedido

{% hint style="info" %}
Implementar somente se for necessário no escopo do seu projeto.
{% endhint %}

É possível aceitar ou recusar um pedido através de chamadas de API, note, entretanto, que se utilizar estas funções o programa CCM Pedidos não deve ser usado, ou seja, o sistema PDV fica responsável por capturar todos os pedidos e fazer todo o controle da loja. O campo de mensagem é opcional.

| Função            | Descrição       |
| ----------------- | --------------- |
| **aceitarPedido** | Aceita o pedido |
| **recusarPedido** | Recusa o pedido |

**Chamada**

```
wsccm.php?token=<SEUTOKEN> &funcao= recusarPedido&pedido=123&msg=Sem-motivo
```

**Retorno**

```
{"resultado":"ok"}
```

## **Status de acompanhamento**

{% hint style="info" %}
Implementar somente se for necessário no escopo do seu projeto.
{% endhint %}

> É possível alterar o status de acompanhamento de um pedido através de chamadas da API (*não confundir com status do pedido*) um pedido pode ter o status de acompanhamento alterado para os valores descritos na tabela abaixo.

| **Valor** | Descrição                                 |
| --------- | ----------------------------------------- |
| 5         | Saiu para entrega ou Pronto para retirada |
| 6         | Pedido entregue ou retirado (finalizado)  |

**Chamada**

```
wsccm_v2.php?token=<SEUTOKEN> &funcao=updateStatus&pedido=332&valor=5
```

**Retorno**

```
A String “OK” é retornada se a operação for executada com sucesso.
```

## Notificações Push

> Implementar somente se for necessário no escopo do seu projeto.

Notificações Push são mensagens enviadas ao aplicativo do cliente. Quando um pedido é aceito/recusado ou tem o status de acompanhamento alterado via API, as notificações padrões são ignoradas, sendo assim fica o sistema PDV responsável por efetuar as chamadas de API com o conteúdo das notificações.

{% hint style="info" %}
Função “**pushCliente**” – Envia notificações para um único cliente.
{% endhint %}

| Campo             | Descrição                                                                             |
| ----------------- | ------------------------------------------------------------------------------------- |
| **codCliente \*** | Código do cliente na plataforma CCM, este pode ser encontrado no cabeçalho do pedido. |
| **titulo \***     | Título da notificação com no máximo 60 caracteres.                                    |
| **msgPush \***    | Mensagem a ser enviada, com limite de 255 caracteres.                                 |

{% hint style="info" %}
Função “**pushGlobal**” – Envia notificações para todos os clientes, usada para fins promocionais.
{% endhint %}

| Campo          | Descrição                                             |
| -------------- | ----------------------------------------------------- |
| **titulo \***  | Título da notificação com no máximo 60 caracteres.    |
| **msgPush \*** | Mensagem a ser enviada, com limite de 255 caracteres. |

**Chamada**

```
wsccm_v2.php?token=<SEUTOKEN>&funcao=pushCliente&msgPush=Notificacao&titulo=123&cod
Cliente=20
```

**Retorno**

```
{"message_id":8660041029282593726}
```

## **Exemplos**

**Listagem de todos os pedidos.**

```
http://api.ccmpedidoonline.com.br/wsccm_v2.php?token=?
```

**Listagem de um único pedido.**

```
http://api.ccmpedidoonline.com.br/wsccm_v2.php?token=?&getnropedido=?
```

**Pedido já importado pelo sistema PDV**

```
http://api.ccmpedidoonline.com.br/wsccm_v2.php?token=?&import=?
```

> XML Listagem de um pedido

```
<pedidos>
    <pedido>
        <nroPedido>2</nroPedido>
        <retira>0</retira>
        <ValorTotal>62.40</ValorTotal>
        <ValorTaxa>5.00</ValorTaxa>
        <TrocoPara>100.00</TrocoPara>
        <CodPdvPagamento>0</CodPdvPagamento>
        <DescricaoPagamento>Dinheiro</DescricaoPagamento>
        <ObsGeraisPedido/>
        <CodigoFilial>6</CodigoFilial>
        <cliente>
            <codigo>1411</codigo>
            <nome>asas as as</nome>
            <telefone>516516151</telefone>
            <email>sasa@assas.com</email>
        </cliente>
        <endereco>
            <rua>rua um</rua>
            <numero>221</numero>
            <complemento/>
            <referencia>casa branca</referencia>
            <bairro>Centro</bairro>
            <cidade>Rio de Janeiro</cidade>
            <estado>RJ</estado>
        </endereco>
        <itens>
            <item>
                <parte>
                    <CodPdvItem>28</CodPdvItem>
                    <ObsParte>Obs no 1 item</ObsParte>
                    <CodPdvGrupo>15</CodPdvGrupo>
                </parte>
                <parte>
                    <CodPdvItem>51</CodPdvItem>
                    <ObsParte/>
                    <CodPdvGrupo>15</CodPdvGrupo>
                </parte>
                <Codigo>3</Codigo>
                <CodPdv/>
                <CodPdvGrupo/>
                <Descricao>BACON / BANANA</Descricao>
                <Quantidade>1</Quantidade>
                <ValorUnit>30.40</ValorUnit>
                <ObsItem/>
                <adicionais>
                    <adicional>
                        <Codigo>120</Codigo>
                        <CodPdv/>
                        <Descricao>Cream cheese</Descricao>
                        <Quantidade>1</Quantidade>
                        <ValorUnit>10.00</ValorUnit>
                    </adicional>
                    <adicional>
                        <Codigo>119</Codigo>
                        <CodPdv/>
                        <Descricao>Chester</Descricao>
                        <Quantidade>1</Quantidade>
                        <ValorUnit>9.00</ValorUnit>
                    </adicional>
                    <adicional>
                        <Codigo>118</Codigo>
                        <CodPdv/>
                        <Descricao>Cheddar</Descricao>
                        <Quantidade>1</Quantidade>
                        <ValorUnit>8.00</ValorUnit>
                    </adicional>
                </adicionais>
            </item>
        </itens>
    </pedido>
```

## Ambiente de homologação

O aplicativo Pizzaria Ramalho deve ser utilizado para testes de integração.

> **Token de acesso:**         A4S5E8C7G7X8F9D5C2S4D5W7Q8C1D4587\
> **Link Google Play:**         <https://bit.ly/AppPizzariaRamalho>\
> **Link Apple Store:**          <https://bit.ly/AppPizzariaRamalhoIos>

## Notificar problemas ao CCM Pedidos

{% hint style="info" %}
Implementar somente se for necessário no escopo do seu projeto.
{% endhint %}

> Em algumas situações adversas o sistema PDV não poderá importar um pedido feito na plataforma CCM, para estes casos deve ser enviada uma notificação com detalhes do problema, desta forma além de preparar o pedido a tempo para o cliente, o erro poderá ser solucionado definitivamente no sistema retaguarda da CCM ou no sistema PDV. Toda notificação de problema será acatada pelo programa CCM Pedidos, que deve alertar o operador do caixa e solicitar a inclusão manual do pedido no sistema PDV.

**Parâmetros de entrada**

| **Campo**   | Descrição                       |
| ----------- | ------------------------------- |
| **token**   | Token de acesso                 |
| **nPedido** | Número do pedido no sistema CCM |
| **error**   | 1                               |
| **reason**  | Detalhes do problema em texto   |

**Respostas**

> Excepcionalmente neste caso a resposta sempre será no formato JSON.

```
{"Status": "OK","nPedido": 1}
{"Status": "Error"}
```

**Exemplo de requisição**

```
wsccm.php?token=...&error=1&nPedido=...&reason=Sem Cod.PDV Produto COCA COLA 2L
```

## Dúvidas frequentes

<details>

<summary>Existe um limite de requisições?</summary>

Sim, segue abaixo a tabela de Rate limiting.

**Pooling de Pedidos**: 3 Requisições por minuto

**Obter dados do pedido (getnropedido)**: 10 Requisições por minuto

**Notificações Push**: 20 Requisições  por minuto

**Abertura da loja**: 3 Requisições por minuto

</details>

***

## Ficou com alguma dúvida?

Ficou com alguma dúvida? Entre em contato agora mesmo pelo nosso numero abaixo ou por e-mail!

* **Telefone/Whatsapp:** (17)99197-0540
* **E-mail:** <suporte@ccmpedidoonline.com.br>

<figure><img src="/files/VYOm25LR2IH6NS76PZgn" alt="" width="188"><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ajuda.ccmpedidoonline.com.br/documentacao-e-integracoes/manual-de-integracao-do-parceiro.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.