Changeset 30655 in project for wiki/eggref/4/correios


Ignore:
Timestamp:
04/06/14 22:37:20 (7 years ago)
Author:
arthurmaciel
Message:
 
File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/correios

    r30199 r30655  
    1313[[/users/arthurmaciel|Arthur Maciel]]
    1414
    15 === Repository
    16 
    17 The git repository for the correios source code is hosted by GitHub:
    18 [[https://github.com/arthurmaciel/correios|https://github.com/arthurmaciel/correios]].
    19 
    2015=== Requirements
    2116
     
    2419=== Documentation
    2520
    26 ==== Data-structures
     21==== Requests
    2722
    28 <record>request</record>
     23<procedure>(make-request #!key service from-zip to-zip (company "") (password "") (pkg-weight 0.3) (pkg-format 1) (pkg-length 16) (pkg-height 2) (pkg-breadth 11) (pkg-diameter 0) (receiver-id-check #f) (declared-value 0) (return-receipt #f) (return-url "XML"))</procedure>
     24Create a correios {{request}} object (a [[defstruct]] record) to be processed. It has many attributes that correspond to the official [[http://www.correios.com.br/webServices/PDF/SCPP_manual_implementacao_calculo_remoto_de_precos_e_prazos.pdf|Correios web service specification]]:
    2925
    30 This is a correios request object to be created and processed. It is a [[defstruct]] record and has a constructor {{make-request}}. It has many accessors that correspond to the official [[http://www.correios.com.br/webServices/PDF/SCPP_manual_implementacao_calculo_remoto_de_precos_e_prazos.pdf|Correios web service specification]]:
     26; SERVICE: available delivery services: {{'PAC}}, {{'SEDEX}}, {{'SEDEX-10}}, {{'SEDEX-HOJE}} and {{'SEDEX-A-COBRAR}}. It can also be a list combining one or more of these symbols (ie. {{'(PAC SEDEX SEDEX-10)}}).
     27; FROM-ZIP: sender's zip code and should be a string with 8 digits (only numbers allowed).
     28; TO-ZIP: receiver's zip code and should be a string with 8 digits (only numbers allowed).
     29; COMPANY: company code, if yours has one. It should be a string.
     30; PASSWORD: company password, only if a company code is provided. It should be a string.
     31; PKG-WEIGHT: package weight in kilograms. Should be a number.
     32; PKG-FORMAT: package format and should be a number: 1 for box/package, 2 for roller/prism and 3 for envelope.
     33; PKG-LENGTH: package length in centimeters (including packing size) and should be a number.
     34; PKG-HEIGHT: package height in centimeters (including packing size) and should be a number.
     35; PKG-BREADTH: package breadth in centimeters (including packing size) and should be a number.
     36; PKG-DIAMETER: package diameter in centimeters (including packing size) and should be a number.
     37; RECEIVER-ID-CHECK: a boolean and determines whether the package should be delivered only to the receiver's hand (Correios calls this service "Mão própria").
     38; DECLARED-VALUE: package declared value in Brazillian Reais, to be returned in case of miscarriage. It should be a number - ex.: {{33.50}} (default is {{0}}, which means no use of service).
     39; RETURN-RECEIPT: a boolean and determines whether the package should be delivered with additional service of a return receipt ({{#f}} means no use of the service).
     40; RETURN-URL: request return URL or type - at the moment can only be "XML".
    3141
    32 '''Note:''' although all values returned use Brazillian decimal notation with a comma separating cents from integers (ex.: {{3,25}}), all the decimal values provided to the constructor should have a dot (ex.: {{3.25}}) separating those parts.
     42'''Note:''' although all values returned use Brazillian decimal notation with a comma separating cents from integers (ex.: {{3,25}}), all the decimal values provided to {{make-request}} should have a dot (ex.: {{3.25}}) separating those parts.
    3343
    34 ; request-service : Available delivery services - PAC, SEDEX, SEDEX-10, SEDEX-HOJE and SEDEX-A-COBRAR. Should be a symbol or a list of symbols - ex.: {{'PAC}}  or {{'(PAC SEDEX SEDEX-10)}}.
    35 ; request-from-zip : Sender zip code. Should be a string with 8 digits (only numbers are allowed).
    36 ; request-to-zip : Receiver zip code. Should be a string with 8 digits (only numbers are allowed).
    37 ; request-company : Company code, if yours has one. Should be a string (default is {{""}}).
    38 ; request-password : Company password, only if a company code is provided. Should be a string (default is {{""}}).
    39 ; request-pkg-weight : Package weight in kilograms. Should be a number (default is {{0.3}}).
    40 ; request-pkg-format : Package format. Should be a number: 1 for box/package, 2 for roller/prism and 3 for envelope (default is {{1}}).
    41 ; request-pkg-length : Package length in centimeters, including packing size. Should be a number (default is {{16}}).
    42 ; request-pkg-height : Package height in centimeters, including packing size. Should be a number (default is {{2}}).
    43 ; request-pkg-breadth : Package breadth in centimeters, including packing size. Should be a number (default is {{11}}).
    44 ; request-pkg-diameter : Package diameter in centimeters, including packing size. Should be a number (default is {{0}}).
    45 ; request-receiver-id-check : If package should be delivered only to the receiver (Correios calls this service "Mão própria"). Should be a boolean (default is {{#f}}).
    46 ; request-declared-value : Package declared value in Brazillian Reais, to be returned in case of miscarriage. Should be a number - ex.: {{33.50}} (default is {{0}}, which means no use of service).
    47 ; request-return-receipt : If package should be delivered with additional service of a return receipt. Should be a boolean (default is {{#f}}, which means no use of service).
    48 ; request-return-url : The request return type - at the moment can only be "XML".
     44<procedure>(update-request old-request #!key service from-zip to-zip company password pkg-weight pkg-format pkg-length pkg-height pkg-breadth pkg-diameter receiver-id-check declared-value return-receipt return-url)</procedure>
     45Like make-request, except this takes an old-request object as a template for values which are missing from the parameter list, thereby providing a way to do a purely functional update of that object.
     46
     47<procedure>(process-request REQUEST)</procedure>
     48This is the core procedure for shipping cost calculation. It accepts a {{request}} object as a parameter and returns a ''list'' of {{response}} objects. The list can be processed (see [[#examples|Examples]] below) and data can be extracted from each response using its accessors (see [[#responses|{{response}}]] details below).
     49
     50For each {{request}} attribute there is a respective accessor procedure:
     51
     52<procedure>(request-service REQUEST) => SERVICE</procedure>
     53<procedure>(request-from-zip REQUEST) => FROM-ZIP</procedure>
     54<procedure>(request-to-zip REQUEST) => TO-ZIP</procedure>
     55<procedure>(request-company REQUEST) => COMPANY</procedure>
     56<procedure>(request-password REQUEST) => PASSWORD</procedure>
     57<procedure>(request-pkg-weight REQUEST) => PKG-WEIGHT</procedure>
     58<procedure>(request-pkg-format REQUEST) => PKG-FORMAT</procedure>
     59<procedure>(request-pkg-length REQUEST) => PKG-LENGTH</procedure>
     60<procedure>(request-pkg-height REQUEST) => PKG-HEIGHT</procedure>
     61<procedure>(request-pkg-breadth REQUEST) => PKG-BREADTH</procedure>
     62<procedure>(request-pkg-diameter REQUEST) => PKG-DIAMETER</procedure>
     63<procedure>(request-receiver-id-check REQUEST) => RECEIVER-ID-CHECK</procedure>
     64<procedure>(request-declared-value REQUEST) => DECLARED-VALUE</procedure>
     65<procedure>(request-return-receipt REQUEST) => RETURN-RECEIPT</procedure>
     66<procedure>(request-return-url REQUEST) => RETURN-URL</procedure>
     67
     68==== Responses
    4969
    5070<record>response</record>
    5171
    52 This is a correios shipping response object that is generated by {{process-request}}. It is a [[defstruct]] record and has a constructor {{make-response}}. It has many accessors that correspond to the official [[http://www.correios.com.br/webServices/PDF/SCPP_manual_implementacao_calculo_remoto_de_precos_e_prazos.pdf|Correios web service specification]] (see the {{request}} record above for details):
     72This is a correios shipping response object that is generated by {{process-request}}. It is a [[defstruct]] record and has a constructor {{make-response}} (used only internally). It has 10 attributes that can be retrieved using the respective accessor procedure:
    5373
    54 ; response-service : symbol - ex.: {{'PAC}}, {{'SEDEX}} or {{SEDEX-10)}}.
    55 ; response-cost : string - total delivery cost in Brazillian Reais - ex.: {{15,80}}.
    56 ; response-delivery-time : number - representing days.
    57 ; response-receiver-id-check-cost : string - cost of this service in Brazillian Reais - ex.: {{3,20}}
    58 ; response-return-receipt-cost : string - cost of this service in Brazillian Reais - ex.: {{2,90}}
    59 ; response-declared-value-cost : string - cost of this service in Brazillian Reais - ex.: {{32,50}}
    60 ; response-home-delivery : boolean - indicates if home delivery is available (believe or not there are many inaccessible areas in Brazil!) - ex.: {{#f}}.
    61 ; response-sunday-delivery : boolean - indicates if delivery on sundays is available - ex.: {{#t}}.
    62 ; response-error : string - indicates error number. Returns {{"0"}} if no error or other number if so (see pages 14 and 15 of the [[http://www.correios.com.br/webServices/PDF/SCPP_manual_implementacao_calculo_remoto_de_precos_e_prazos.pdf|Correios web service specification]]).
    63 ; response-error-msg : returns {{#f}} if no error or a string with the error message otherwise.
     74<procedure>(response-service RESPONSE) => SERVICE</procedure>
     75Returns the delivery service type as a symbol - ie. {{'PAC}}, {{'SEDEX}} or {{SEDEX-10)}}.
    6476
    65 ==== Procedures
     77<procedure>(response-cost RESPONSE) => COST</procedure>
     78Returns the total delivery cost in Brazillian Reais as a string - ie. {{"15,80"}}.
    6679
    67 <procedure>(process-request request)</procedure>
     80<procedure>(response-delivery-time RESPONSE) => DELIVERY-TIME</procedure>
     81Returns the delivery time in days as a number.
    6882
    69 This is the core correios procedure for shipping cost calculation. It accepts a {{request}} as a parameter and returns a ''list'' of {{response}}. The list can be processed (see Examples below) and data can be extracted from each response using its accessors (see {{response}} details above).
     83<procedure>(response-receiver-id-check-cost RESPONSE) => RECEIVER-ID-CHECK-COST</procedure>
     84Returns the cost of the {{receiver-id-check}} service (if used) in Brazillian Reais as a string - ie. {{"3,20"}}.
    7085
    71 <procedure>(valid-response? response)</procedure>
     86<procedure>(response-return-receipt-cost RESPONSE) => RETURN-RECEIPT-COST</procedure>
     87Returns the cost of the {{return-receipt-cost}} service (if used) in Brazillian Reais as a string - ie. {{"2,90"}}.
    7288
     89<procedure>(response-declared-value-cost RESPONSE) => DECLARED-VALUE-COST</procedure>
     90Returns the cost of {{declared-value}} service in Brazillian Reais as a string - ie. {{"32,50"}}.
     91
     92<procedure>(response-home-delivery RESPONSE) => HOME-DELIVERY</procedure>
     93Returns a boolean indicating whether or not the {{home-delivery}} service is available (believe it or not there are still many inaccessible areas in Brazil!).
     94
     95<procedure>(response-saturday-delivery RESPONSE) => SATURDAY-DELIVERY</procedure>
     96Returns a boolean indicating whether or not the {{saturday-delivery}} service is available.
     97
     98<procedure>(response-error RESPONSE) => ERROR</procedure>
     99Returns {{"0"}} if there were no errors or other number (in a string format) if so (see pages 14 and 15 of the [[http://www.correios.com.br/webServices/PDF/SCPP_manual_implementacao_calculo_remoto_de_precos_e_prazos.pdf|Correios web service specification]] for a complete error code list).
     100
     101<procedure>(response-error-msg RESPONSE) => ERROR-MSG</procedure>
     102Returns a {{#f}} if there were no errors or a string with the error message.
     103
     104There is also a procedure to check if there {{response}} generated by {{process-request}} is valid:
     105
     106<procedure>(valid-response? RESPONSE)</procedure>
    73107Check if a specific response has generated errors. Returns a boolean.
    74108
    75 === Examples
    76 
     109===== Examples
    77110<enscript highlight="scheme">
    78111(use correios)
Note: See TracChangeset for help on using the changeset viewer.