📚Manual de integração do Parceiro

API de integração de Pedidos e status do estabelecimento.

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

Acesso a API (Versão 2)

Endereço: https://api.ccmpedidoonline.com.br/wsccm_v2.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

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

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	[e-mail]
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.

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)

Note que esta implementação pode ser ignorada caso opte em manter o programa CCM Pedidos visível para o usuário.

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

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

É 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

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

É 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.

Função “pushCliente” – Envia notificações para um único cliente.

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.

Função “pushGlobal” – Envia notificações para todos os clientes, usada para fins promocionais.

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>[e-mail]</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

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

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

Existe um limite de requisições?

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

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: [phone]

• E-mail: [e-mail]